(12) INTERNATIONAL APPLICATION PUBLISHED UNDER THE PATENT COOPERATION TREATY (PCT) 



(19) World Intellectual Property Organization 
International Bureau 

(43) International Publication Date 
29 November 2001 (29.11.2001) 




PCT 



(10) International Publication Number 

WO 01/90884 A2 



(51) International Patent Classification 7 : GO6F9/00 

(21) International Application Number: PCT/US01/16101 

(22) International Filing Date: 17 May 2001 (17.05.2001) 
(25) Filing Language: English 
(261 Publication Language: English 



(30) Priority Data: 

09/578,528 



24 May 2000 (24.05.2000) US 



(71) Applicant: SUN MICROSYSTEMS, INC. [US/US], 901 
San Antonio Road, Palo Alto, CA 94303 (US). 

(72) Inventor: SHARMA, Rahul; 1035 Aster Avenue, #3146, 
Sunnyvale, CA 94086 (US). 

(74) Agents: CASERZA, Steven, F. et aL; FlehrHohbach Test 
ATbritlon & Herbert LLP, Suite 3400, 4 Embarcadero Cen- 
ter, San Francisco, CA 9411 1-4187 (US). 



(81) Designated States (national): AE, AG, AL, AM, AT, AU, 
AZ, BA, BB, BG. BR, BY, BZ, CA, CH, CN, CO, CR, CU, 
CZ, DE, DK, DM, DZ, EC, EE, ES, FI, GB, GD, GB, GH, 
GM, HR, HU, ID, IL, IN, IS, JP, KE, KG, KP, KR, KZ, LC, 
LK, LR, LS, LT, LU, LV, MA, MD, MG, MK, MN, MW, 
MX, MZ, NO, NZ, PL, PT, RO. RU, SD, SE, SG, SI, SK, 
SL, TJ, TM, TR, TT, TZ, UA, UG. UZ, VN, YU, ZA , ZW. 

(84) Designated States (regional): ARIPO patent (GH, GM, 
KE, LS, MW, MZ, SD, SL, SZ, TZ, UG, ZW), Eurasian 
patent (AM, AZ, BY, KG, KZ, MD, RU, TJ, TM), European 
patent (AT, BE, CH, CY, DE, DK, ES, FI, FR, GB, GR« IE, 
IT, LU, MC, NL, PT, SE, TRX OAH patent (BF, BJ, CP, 
CG, a CM, G A, GN, GW, ML, MR, NE, SN. TD, TG). 

Published: 

— without international search report and to be republished 
upon receipt of that report 

For two-letter codes and other abbreviations, refer to the "Guid- 
ance Notes on Codes and A bbreviations " appearing at the begin- 
ning of each regular issue of the PCT Gazette, 



= (54) Title: MODULAR AND PORTABLE DEPLOYMENT OF A RESOURCE ADAPTER IN AN APPLICATION SERVER 




o 



(57) Abstract: A system by which resource adapters 
may be utilized in client server computer configurations 
utilizing enterprise information systems is disclosed. A 
connector provider develops a set of Java interfaces and 
classes as part of its implementation of a resource adapter. 
These Java classes implement connector architecture 
specified contracts and implement BIS specific 
functionality provided by the resource adapter. The 
development of a resource adapter can also require use 
of native Hbraries mat are specific to the underlying BIS. 
The Java interfaces and classes and native Hbraries, help 
files, documentation and other resources (as necessary) 
are then packaged together with a deployment descriptor 
to create a resource adapter module. The resource adapter 
module defines the contract between a connector provider 
and deployer for the deployment of a resource adapter 
in the client server environment In order to facilitate the 
configuration of the resource adapter in an operational 
environment, the present invention specifies the following 
interfaces and classes. A class mat implements a managed 
connection factory class supports a set of properties that 
provide information required by the managed connection 
factory for the creation of physical connections to the 
underlying EIS. This implementation class provides 
getter and setter methods for each of its supported 
properties. The supported properties are consistent with 
the specification of configurable properties specified in 
the deployment descriptor. 
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MODULAR AND PORTABLE DEPLOYMENT OF A RESOURCE 
ADAPTER IN AN APPLICATION SERVER 

FIELD 

The present relates broadly to computer systems having a client server 
configuration. Specifically, the present invention relates to resource adapters used in client 
server applications. More specifically still, the present invention relates to a modular and 
5 portable deployment of resource adapters in client server applications. 

BACKGROUND 

An enterprise information system (EIS) provides an information infrastructure to an 
enterprise in a client-server computer system configuration. An EIS offers a set of services 

10 to its clients. These services are exposed to clients as local and/or remote interfaces. A 
resource manager is a software module that manages a set of shared EIS resources. For 
example, a transactional resource manager can participate in transactions that are externally 
controlled and coordinated by a transaction manager. 

A resource adapter is a system level software driver provided along with an EES 

15 connector and is specific to an underlying EIS. A resource adapter is used by an application 
server or an application client to connect to the EIS. The resource adapter plugs into an 
application server and collaborates with the application server to provide the underlying 
mechanisms- transactions, security, and connection pooling. 

There is currently no existing standard mechanism for deploying and configuring 

20 resource adapters in a managed application server environment Each vendor has its own 
specific mechanism, making it difficult to achieve off-the-shelf phiggability of resource 
adapters in an application server. For application developers who design and implement 
application servers, the result is an enormous amount of duplicated or nearly duplicated 
effort expended to customize resource adapters into a specific client server configuration. 
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SUMMARY 

The present invention provides a standardized system by which resource adapters 
may be utilized in client server computer configurations utilizing enterprise information 
systems. A connector provider develops a set of Java interfaces and classes as part of its 
5 implementation of a resource adapter. These Java classes implement connector architecture 
specified contracts and implement EIS specific functionality provided by the resource 
adapter. The development of a resource adapter can also require use of native libraries that 
are specific to the underlying EIS. The Java interfaces and classes and native libraries, help 
files, documentation and other resources (as necessary) are then packaged together with a 

10 deployment descriptor to create a resource adapter module. The resource adapter module 
defines the contract between a connector provider and deployer for the deployment of a 
resource adapter in the client server environment 

In order to facilitate the configuration of the resource adapter in an operational 
. environment, the present invention specifies the following interfaces and classes. A class 

1 5 that implements a managed connection factory class supports a set of properties that provide 
information required by the managed connection factory for the creation of physical 
connections to the underlying EIS. This implementation class provides getter and setter 
methods for each of its supported properties. The supported properties are consistent with 
the specification of configurable properties specified in the deployment descriptor. 

20 A preferred embodiment of the present invention incorporates an environment using 

the Java Naming and Directory Interface (JNDI). An application component or client is 
required to look up a connection factory instance in the component's environment using the 
JNDI interface. The application component then uses the connection factory instance to get 
a connection the underlying EIS. Registration of a connection factory instance in the JNDI 

25 namespace can be done by using either JNDI reference or serializable mechanisms. 

BRIEF DESCRIPTION OF THE DRAWINGS 

FIG. 1 is a high level block diagram of the major components utilized in a computer 
system according to the present invention; and 
30 FIG. 2 is a high level block diagram of the major software components utilized in a 

client server computer environment incorporating an enterprise information system. 
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DETAILED DESCRIPTION 

The present invention specifies requirements for packaging and deploying of a 
resource adapter. These requirements support a modular and portable deployment of a 
resource adapter into a J2EB compliant application server. 
5 FIG. 1 is a high level block diagram of the hardware typically used in an 

embodiment of the present invention. Computer 150 incorporates a processor 152 utilizing 
a central processing unit (CPU) and supporting integrated circuitry. Memory 154 may 
include RAM and NVRAM such as flash memory, to facilitate storage of software modules 
executed by processor 152, such as the resource adapter of the present invention. Also 

10 included in computer 150 are keyboard 158, pointing device 160, and monitor 162, which 
allow a user to interact with computer 150 during execution of programs. Mass storage 
devices such as disk drive 164 and CD ROM 166 may also be included in computer 150 to 
provide storage for resource adapter and associated files. Computer 150 may communicate 
with other computers via modem 168 and telephone line 170 to allow application server or 

15 EIS to be operated remotely, or utilize files stored at different locations. Other media may 
also be used in place of modem 1 68 and telephone line 1 70, such as a direct connection or 
high speed data line. The components described above may be operatively connected by a 
communications bus 172. 

20 Overview 

A connector provider develops a set of Java interfaces/classes as part of its 
implementation of a resource adapter 202. These Java classes implement connector 
architecture specified contracts and implement EIS specific functionality provided by the 
resource adapter 202. The development of a resource adapter 202 can also require use of 
25 native libraries that are specific to the underlying EIS 204. The Java interfaces/classes are 
thai packaged together (with required native libraries, help files, documentation and other 
resources) with a deployment descriptor to create a Resource Adapter Module 206. A 
deployment descriptor defines the contract between a connector provider and deployer for 
the deployment of a resource adapter 202. 
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A resource adapter module 206 corresponds to a J2EE module in terms of the J2EE 
composition hierarchy. A J2EB module represents the hasic unit of composition of a J2EB 
application. Examples of J2EE modules include: EJB module, application client module, 
web client module. A resource adapter module 206 can be deployed either directly into an 
5 ^plication server 208 as a stand alone unit, or with a J2EE application that consists of one 
or more J2EB modules in addition to a resource adapter module 206. The J2EE 
specification specifies requirements for the assembly and packaging of J2EE applications. 
The stand alone deployment of a resource adapter module 206 into an application server 208 
is typically done to support scenarios in which multiple J2EE applications share a single 
10 resource adapter module. However in certain scenarios, a resource adapter module 206 will 
only be required by components within a single J2EE application. The deployment option 
of resource adaptor module 206 bundled with a J2EE application supports fee latter 
scenario. During the deployment, the deployer installs a resource adapter module 206 in an 
application server 208 and then configures it in the target operational environment 

15 

Packaging 

The file format for a packaged resource adapter module 206 defines the contract 
between a connector provider and deployer. A packaged resource adapter 202 includes Java 
classes and interfaces that are required for the implementation of both connector contracts 

20 and functionality of the resource adapter 202; utility Java classes for the resource adapter 
202 ; native libraries required by the resource adapter 202; and any help files and 
documentation and descriptive meta information that ties all of the above elements together. 
In file preferred embodiment, a resource adapter 202 is be packaged using the Java ARchive 
(JAR) format into a resource adapter archive (RAR). For example, a resource adapter for 

25 EIS Acanbe packaged as an archive with a filename eisAjnar. The RAR file is structured 
as a hierarchical directory as follows. /RA-INF/rajanl is a deployment descriptor. /RA- 
INF/classes/* is a directory containing Java interfaces, implementation and utility classes as 
required by the resource adapter 202. /RA-INF/native-Kb/* is a directory containing any 
native libraries used by the resource adapter 202. Any platform dependent libraries are in 

30 this directory. 
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The RAR file contains a deployment descriptor based on the format specified in the 
section. The deployment descriptor is stored with the name RA-INF/ra-xml in theRAR file. 
A resource adapter packaged as a RAR file contains a META-INF directory that contains 
information useful to the Java Archive tools. 

5 

Deployment 

A deployment descriptor defines the contract between a connector provider and 
deployed It captures the declarative information that is intended for the deployer for 
deployment of a resource adapter in a target operational environment A resource adapter 
10 module 206 is deployed based on the deployment requirements specified by the connector 
provider through the deployment descriptor. 

Connector Provider's Responsibility 

The connector provider specifies the deployment descriptor for a resource adapter 

15 202. The connector provider specifies general information about a resource adapter, such 
as the name of the resource adapter, a description of the resource adapter, aURI of aUI 
icon for the resource adapter, and the identity of the vendor who provides the resource 
adapter. The connector provider can also specify the type of EIS system, such as the name 
of a specific database, ERP system, etc. Additionally, the connector provider can specify the 

20 version of the connector specification (represented as a string) supported by the resource 
adapter, as well as the version of the resource adapter, also represented as a string. 

The connector provider also specifies the folly qualified name of the Java class that 
implements the javaxjesourceManagedConnectionFactory interface, as well as the fully 
qualified name of the Java interface and implementation class for the connection factory. 

25 The connector provider specifies the fully qualified name of the Java interface and 

implementation class for the connection interface. The connector provider specifies the 
level of transaction support provided by the resource adapter implementation. The level of 
transaction support can be any one of the following: ^^transaction, local transaction or 
xa_transaction. Note that this support is specified for a resource adapter and not for the 

30 underlying EIS instance. no__transaction indicates that the resource adapter 202 does not 
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support either resource manager local or JTA transactions. It does not implement either 
XAResource or LocalTransaction interfaces. 

local ^transaction indicates that the resource adaptor 202 supports resource manager 
local transactions by implementing the LocalTransaction interface. 
5 xajransaction indicates that the resource adapter 202 supports both resource 

manager local and JTA transactions by implementing the LocalTransaction and 
XAResource interfaces respectively. 

The connector provider specifies name, type, description and an optional default 
value for the properties that have to be configured on a per ManagedConnectionFactoiy 
10 instance. Each ManagedConnectionFactory instance creates connections to a specific BIS 
instance based on the properties configured on the ManagedConnectionFactory instance. 
The configurable properties are specified only once in the deployment descriptor, even 
though a resource adapter 202 can be used to configure multiple 

ManagedCommectionFactory instances (that create connections to different instances of the 
15 sameEIS). For example, a deployment tool can create multiple copies of XML based 
deployment descriptor; each copy of the deployment descriptor carries a specific 
configuration of properties for a ManagedConnectionF actory. 

Authentication Mechanism 

20 The connector provider specifies all the authentication mechanisms that are 

supported by the resource adapter 202. This relates to the support provided by the resource 
adapter 202 implementation but not by the underlying EIS instance. The standard values 
are: basicpassword and kerbvS. The resource adaptor 202 can support one or more of these 
authentication mechanisms. Basicpassword is a user password based authentication 

25 mechanism that is specific to an EIS Kerbv5 is a Kerberos version 5 based authentication 
mechanism. If there is no authentication mechanism specified as part of the deployment 
descriptor, the resource adapter 202 does not support any standard security authentication 
mechanisms as part of security contract 

The connector provider specifies whether resource adapter 202 supports 

30 reauthentication of an existing physical connection. The security permission listed in the 
deployment descriptor are different from those required by the default permission set The 
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deployment descriptor specified by the connector provider for its resource adapter is 
consistent with the XML document type description (DTD) as specified below. 

Deployer Responsibilities 
5 The deployer is responsible for using a deployment tool to configure a resource 

adapter 202 in a target operational environment The configuration of a resource adapter 202 
is based on the properties defined in the deployment descriptor as part of the resource 
adapter module 206. The deployer performs the following tasks to configure a resource 
adapter 202. 

10 The deployer configures one or more property sets (per ManagedConnectionFactory 

instance) for creating connections to various underlying BIS instances. The deployer 
creates a property set by using a deployment tool to set valid values for various configurable 
fields. The configuration of each field is based on the name, type and description of the 
field specified in the deployment descriptor. 

15 Each property set represents a specific configuration for creating connections to a 

specific EIS instance. Since a resource adapter 202 can be used to create connections to 
multiple instances of the same EIS, there can be multiple property sets (one for each 
configured instance of the object ManagedConnectionFactory) for a single resource adapter 
202. 

20 The deployer also configures application server 208 mechanisms for transaction 

management based on die level of transaction support specified by the resource adapter 202. 
Additionally, the deployer configures security in the target operational environment based 
on the security requirements specified by the resource adapter 202 in its deployment 
descriptor. During deployment, the deployer can check whether or not an underlying EES 

25 instance supports the same capabilities such as transaction support and authentication 

mechanisms as the corresponding resource adapter 202. For example, if a resource adapter 
202 provides implementation support for Kert>eros based authentication but the underlying 
EIS instance does not support Kerberos, then the deployer can decide not to configure 
Kerberos for authentication to this EIS instance. However if the deployer does not perform 

30 such checks during deployment, any misconfigurations should lead to runtime exceptions. 
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Application Server Responsibilities 

An application server 208 provides a deployment tool that supports deployment of 
multiple resource adapters. A deployment tool can also be provided by third party 
enterprise tools vendors. A deployment tool is capable of reading the deployment 
5 descriptor from a resource adapter module 206. It enables the deployer to configure a 
resource adapter 202 in the operational environment and thereby reflect the values of all 
properties declared in the deployment descriptor for the resource adapter 202. A 
deployment tool supports management of multiple property sets (one per configured 
ManagedConnectionFactory instance) for a resource adapter 202. This includes support for 

10 adding or removing a property set from fee configuration for a resource adapter 202. 

A deployment tool supports addition and removal of resource adapters from an 
operational environment An application server 208 uses the deployment properties about 
the capabilities of a resource adapter 202 (for example, support level for transactions) to 
provide different QoS for a configured resource adapter 202 and its underlying EIS. The 

15 preferred embodiment of the present invention incorporates the following interfaces and 
classes. 

ManagedConnectionFactory 

The class that implements ManagedConnectionFactory 212 interface supports a set 

20 of properties that provide information required by the ManagedConnectionfectory 212 for 
the creation of physical connections to the underlying EIS. A resource adapter 202 can 
implement the ManagedConnectionFactory 212 interface as a Java Bean. As a Java Bean 
implemented the resource adapter 202 can also provide aBeanlnfb class that implements 
the javabeans JBeanlhfo interface and provides explicit information about the methods and 

25 properties supported by the ManagedConnectionFactory implementation class. The 

implementation of ManagedConnectionFactory 212 as a Java Bean improves the tool ability 
(for tools that are based on the JavaBeans framework) for the configuration of 
ManagedConnectionFactory instances. In the preferred embodiment, the deployment tool 
uses an XML based deployment descriptor to find out the set of configurable properties for 

30 a ManagedConnectionFactory 212. A deployment descriptor for a resource adapter 202 
specifies name, type, description and default value of the configurable properties. 
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Properties Conventions 

The ManagedConnectionFactory implementation class provides getter and setter 
methods for each of its supported properties. The supported properties are consistent with 
the specification of configurable properties specified in the deployment descriptor. The 
getter and setter methods convention are based on Java Beans design pattern. These 
methods are defined on the implementation class and not on the 
ManagedConnectionFactory interface 212. treason for this requirement is to keep 
ManagedConnectionfactory interface 212 independent of any resource adapter or EIS 
specific properties. 



10 



Standard Properties 

The connector architecture identifies a standard set of properties common across 
various types of resource adapters andEISs. A resource adapter 202 is not required to 
support a standard property if that property does not apply to its configuration. These 
15 standard properties include the name of the server for the EIS instance, the port number for 
establishing connection to an BIS instance, name of the user establishing connection to an 
EIS instance, password for the user establishing connection, and the URL for the EIS 
instance to which to connect 

In addition to these standard properties, a ManagedConnectionFactory 
implementation class can support properties that are specific to a resource adapter and its 
underlying EIS. All the properties are a<mmnstered by me deployer and ate not visible to an 
apptication component provider. It is required that the specified properties be bound within 
specific limits or be restricted to well defined values. In the XML deployment descriptor, 
any bounds or well defined values of properties are described in the description element 



20 



25 



30 



JNDI Configuration and Lookup 

m both managed and nonmanaged application scenarios, an application component 
210 (or application client) looks up a connection factory instance in the component's 
environment using the Java Naming and Directory Interface (JNDI). The application 
component 210 then uses toe connection factory instance to get a connection to the 
underlying EIS. The following code extract example shows the JNDI lookup of a 
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javax.resource.ccLConnectionFactory instance. 
// Application Component/Client Code 
obtain the initial JNDI context 
Context initctx = new InitialContextO; 
5 // perform JNDI lookup to obtain connection factory 
javax.resource.cci.ConnectionFactory cxf = 
(javax.resource.cci.(>imectionFactory)ini^ 

env/eis/MyEIS"); 

javaxjesonrce.cci.Connection cx = cxfgetConnectionO; 

10 In both managed or nonmanaged environment, registration of a connection fectory 

214 instance in the JNDI namespace can be performed by using either JNDI Reference or 
Serializable mechanism. The choice between the two JNDI mechanisms depends on 
whether the JNDI provider being used supports specific mechanism, whether the application 
server 208 and resource adapter 202 provide the necessary support as specified in the 

15 respective requirements, and any constraints on the size of serialized objecte 

stored in the JNDI namespace. The reference mechanism allows for only a reference to the 
actual object to be stored in the JNDI namespace. This is preferable to the serializable 
mechanism that stores the whole serialized object in the namespace. 

20 Deployer 

The deployer is responsible for configuring connection factory instances in the JNDI 
environment The deployer manages the JNDI namespace such that the same programming 
model for JNDI based connection factory lookup is supported in both managed and 
nonmanaged environments. 

25 

Resource Adapter 

The implementation class for a connection factory interface is required to implement 
the java. io.Serializable interface to support JNDI registration. An implementation of 
javaxoiaming. Referenceable interface by connection factory class is only required if the 
30 connection factory 214 supports Reference mechanism-based JNDI registration. The 
ManagedConnectionFactory implementation class is required to implement the 
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java.io.Serializable mterface. To support Reference mechanism in a nonmanaged 
environment, a resource adapter or a helper class is utilized to provide an implementation of 
the javax.naming-spi.ObjectFactory interface. 

5 Application Server 

The implementation class for javaxj^source.ConnectionManagCT is required to 
implement java.io.Serializable interface. If an application server 208 supports JNDI 
Reference mechanism based connection fectory lookup, it is required to provide an 
implementation class for javaxjxaming.spi.ObjectFactory interfece. The implementation of 

10 this interfece is application server specific. 

hi a serializeable scenario, The implementation classes for both javax.resoiiice.- 
cci.ConnectionFactory and ja^axj^urceAianagedConnectionF actory interfaces 
implement java.io.Serializable interfece. The deployment code retrieves the configuration 
properties from the XML deployment descriptor for the resource adapter 202. The 

15 deployment code then creates an instance of ManagedConnectionFactory implementation 
class and configures properties on the instance. An example appears below: 
// Deployment Code 

// Create an instance of ManagedConnectionFactory implementation class 
comjnyeisManagedConnectioiiFactoryln^)! mcf = 
20 new <x>mjnyeis.ManagedC^iinectioiiFactorylmplOi 

// Set properties on ManagedConnectionFactory instance 

// Note: Properties are defined on the implementation class and not on the 

// javax^esource^ManagedConnectiohF actory interface 

mcfsetSenrerNameC"-"); 
25 mcfsrtPortNumberC 4 ... w ); 

... * 

In a non-managed environment, an application developer writes the deployment 
code. While in a managed environment, the deployment code is typically hidden by a 
deployment tooL The deployment code uses the ManagedConnectionFactory instance to 
30 create a connection fectory instance. The code then registers the connection fectory 
instance in the JNDI namespace. 7/ Deployment Code 
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// In managed environment, create a ConnectionManager specific to 
// the application server. Note that in a nonmanaged environment, 
// ConnectionManager is specific to the resource adapter. 
conoLWombatservCT.ConnectionManager cm = 
5 new com.wombatseiver.ConnectionManager(. ..); 
// Create an instance of connection factory 
Object cxf = mc£CTeateConnectionFactoiy(cm); 
// Get JNDI context 

j avax Jiaming-Context ctx = new javax jiamingjnitialContext(env); 
10 //Bind to the JNDI namespace specifying a factory name 
ctx.bind("...", cxf); 

When an application component 210 does a JNDI lookup of connection factory 
instance, the returned connection factory instance is associated with a configured 
ManagedConnectionFactory instance and a ConnectionManager instance. The 
1 5 implementation class for connection factory 214 achieves the association between these 
instances in an implementation specific manner. A JNDI configuration in a managed 
environment can be based on the Reference mechanism, using the Cd interfaces 
javaxjesource.cci.ConnectionF actory and javaxjesource.ccLConnection as connection 
factory214 and connection interface, respectively. 

20 

Scenario: Referenceable 

The implementation class for ConnectionFactory interface 214 implements the 

javax .naming. Referenceable as shown in the following code extract example. 

public class com.myeis.CcmnectionFactoryImpl implements 
25 javax.namingJReferenceable, 

javaio.Serializable, 

javax jresource.cti.ConnectionFactory { 

// Reference to this ConnectionFactory 

javax-naming-Reference reference; 
30 // setReference is called by deployment code 

public void setReference(Reference ref) { 
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reference = ref, 

> 

// getReference is called by JNDI provider during Contextbind 
public Reference getReferenceO throws NamingException { 
5 return reference; 
> 

• •• 

> 

Note that the method setReference is not defined as part of the Referenceable interface. 

10 An application server 208 provides a class (in an application server specific 

implementation) that implements the javaxjiaming.spLObjectFactory interface. In the 
ObjectFactory.getObject-Instance method, the information carried by the Reference 
parameter (as set in the C^nnection-FactorylmpLsetReference method) is used to lookup the 
property set to be configured on the target ManagedConnectionFactory instance. The 

15 mapping from a Reference instance to multiple configured property sets enables an 
application server 208 to configure multiple ManagedConnectionFactory instances with 
respective property sets. An application server 208 m ain t ains the property set configuration 
in an implementation specific way based on die deployment descriptor specification. 

The implementation and structure of Reference is specific to an application server 

20 208. The following code extract shows an ufustratfve example of the 
ObjectFactory.getObjectlnstance method, 
public class comwombatserverwAppKcationServerJr©IHandler 
implements javaxjiammg-spLObjectFactory { 
//... 

25 public Object getObjecQnstance(Object obj, Name name, Context ctx, Hashtable env) 
throws Exception { 

javax namingReference ref = QavaxjiamingJleference)obj; 
// Using the information carried by the Reference instance, 
// (<referenceName, logicaIName> in this example) lookup 
30 // a configured property set and then configure a 

// ManagedConnectionFactory instance with specified 
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//properties. 

// ... [implementation specific] 

// 

// For example: the instantiation of ManagedConnectionFactory 
5 // implementation class and invocation of its setter method 

// can be done using Java Reflection mechanism. 

JavaxjesourceJvlanagedConnectionFactoTy mcf = //... 

// create a Connection Manager instance specific to the 

// application server 
10 com.wombatserv«:.ConnectionManagCT cxManager = // ... 

// create a connection factory instance. 

• // The ConnectionManager instance provided by the application 
// server gets associated with the created 
// connection factory instance 
15 return mcfcreateConnectionFactory(CTManagar); 

> 

> 

The following deployment code example shows registration of a reference to a 
20 connection factory instance in the JNDI namespace:7/ Deployment Code 

javaxjiammg-Context ctx = new javaxj3mnmg.InitialContext(CTLv); 

// Create an instance of connection factory 

comjnyeis.ConnectionFactorylmpl cf = 

new comjnyeis.ConnecticniFactorylmplO; 
25 // Create a reference for the ConnectionF actory instance 

javaxjiaming^eference ref= new javax.nammg.Reference( 

ConnectionFactoryImpLclass.gefNameO, 
new javaxJiaming.StringRefAddr( . 
"<^ferenceName>", "<ogjcaIName>"), 
30 ApplicationSorva:JNDIHandler.class.ge*NameO» 
null); 
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cf.setReference(ref); 

// bind to the JNDI namespace specifying a name for the connection factory 
ctx.bindC...",cf); 

The deployment code is designed as generic. The code dynamically creates an 
5 instance of connection factory 214, create a Reference instance and then set the reference. In 
the above code sample, the setReference method is implementation specific and is not 
defined as part of the Referenceable interface. The Contextbind method registers a 
Reference to the connection factory instance in the JNDI namespace. 

10 Connection Factory Lookup 

The following steps happen when an application component 210 calls the method 
JNDI Context lookup to lookup a connection factory instance. First, the JNDI passes 
control to the application server 208 and the method ObjectFactory. getObjectlnstance 
implemented by the application server 208 is called The application server 208 then 

15 creates a new instance of ManagedConnectionFactory implementation class provided by the 
resource adapter 202. The application server 208 then calls setter methods on the 
ManagedConnectionFactory instance to set various configuration properties on this 
• instance. These properties provide information that is required by the 
ManagedConnectionFactory instance to create physical connections to the underlying EES. 

20 The application servo" 208 uses an existing property set (configured during the deployment 
of resource adapter) to set the required properties on the ManagedConnectionFactory 
instance. 

After the newly created ManagedConnectionFactory instance has been configured 
with its property set, the application server 208 creates a new CormectionManager instance. 
25 The application server 208 then calls the method createConnectionFactory on the 

ManagedConnectionFactory instance (passing in the ConnectionManager instance from the 
previous step) to get a ConnectionFactory instance. 

The application server 208 then returns the connection factory instance to the JNDI 
provider so that this instance can be returned as result of the JNDI lookup. The application 
30 component 210 gets the ConnectionFactory instance as a result of the JNDI lookup. 
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The extensible Markup Language (XML) Document Type Definition (DTD) may be 
used for the deployment descriptor for resource adapter 202. The comments in the DTD 
specify additional requirements for the syntax and semantics that cannot be specified by the 
DTD mechanism. All valid resource adapter deployment descriptors contain the following 
5 DOCTYPE declaration: 

<!DOCTYPE connector PUBLIC "//Sun Microsystems, IncJ/DTD Connector 1 .0/ 
/EN" ^ttp^ava-sun-cop^e^ 

The root element of the deployment descriptor for a resource adapter is the 
connector. The content of the XML elements is usually case sensitive. A resource adapter 

10 (or an application server on behalf of resource adapter 202) can specify additional 
deployment information beyond the standard deployment descriptor. The additional 
information is stored in a separate file and refers to the standard deployment descriptor. 
Resource adapter 202 is not allowed to add any nonstandard information into a standard 
deployment descriptor. 

15 The connector element is the root element of the deployment descriptor for the 

connector. This element includes general information vendor name, version, specification 
version supported, and icon related to the resource adapter module 206. It also includes 
information specific to the implementation of the resource adapter library as specified 
through the element resourceadapter, as shown in the following illustrative example. 

20 > 

<!ELEMENT connector (displayname, description?, icon?, vendomame, specversion, 

eistype, version, resourceadapter)> 

<! 

The dement resourceadapter specifies information about the resource adapter 202 
25 provided by the connector provider. The information includes fully qualified names of 
class/interfaces required as part of die connector architecture specified contracts, level of 
transaction support provided, configurable properties for ManagedCormeciionF actory 
instance, one or more authentication mechanisms supported and additional required security 
permissions. If there is no authentication mechanism specified as part of resource adapter 
30 element the resource adapter 202 does not support any standard authentication mechanisms 
as part of security contract An example of the resourceadapter element appears below. 

> 

<!ELEMENT resourceadapter (managedconnection&ctoryclass, coimecticmfactoryinterface, 
connectionfactoryimplclass, connectioninterfece, cormectionimpl 
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class, transactionsupport, configproperty*, authmechanism*, reauthentication 
support, securitypermission* 

> 
<! 

5 The element authmechanism specifies an authentication mechanism supported by 

the resource adapter 202. Note that this support is for the resource adapter 202 and not for 
the underlying EIS instance. The optional description specifies any.resource adapter specific 
requirement for tjie support of security contract and authentication mechanism. An example 
of the authmechanism element appears below. 

10 > 

<!ELEMENT authmechanism (description?, authmechtype, credentialinlerface+ )> 
<! 

The element credentialinterface specifies the interface that the resource adapter 
implementation supports for the representation of the security credentials. This element is 
1 5 used by application server 208 to find out the Credential interface it should use as part of the 
security contract The possible values are: 

KcredcntiaMtetihc^ 

<ycredentialinteriace> 

<3aiedentialmterface^ 

20 </credentialinterfece> 

> 

<!ELEMENT aredentialinterfece (#PCDATA)> 
<! 

The element authmechtype specifies type of an authentication mechanism. The 
25 possible values are: 

<Snthmechtype>basicpass 
<^tiimechtype>keAv5</aa3thmedityp^ 

> 

<!ELBMENT anthmechtype (#PCDATA)> 
30 <! 
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The element comectionfactoryinterface specifies the fully qualified name of the 
ConnectionFactory interface supported by the resource adapter 202. An example appears 
below. 

<^nnection^tox>dnteiface>javaxj^souiw.cci. ConnectionFactory 
5 </connectionfectoryinterfece> 
> 

<!ELEMENT connectionfectoryinterfece (#PCDATA)> 
<! 

The element connectionfactoryimplclass specifies the fully qualified name of the 
10 ConnectionFactory class that implements resource adapter specific ConnectionFactory 
interface. 

Example:<tannectionfactoiy^ 
</connectionfectoryimplclass> 
> 

15 <!ELEMENT connectionfactoryimplclass (#PCDATA)> 
<! 

The element connectioninterface specifies the fully qualified name of the 
Connection interface supported by the resource adapter 202. 

Example: <^rmectiomnterface>javax^ 

20 <Vcoimectioninterface> 

>.<!ELEMENT comectioninterfece (#PCDATA)> 

<! 

The element connectionimplclass specifies flie fully qualified name of the 
Connection class that implements resource adapter specific Connection interface. 

25 Example: <^nnectionimplclass>conxwom 

</connectionimplclass> 

> 

<!ELEMENT connectionimplclass (#PCDATA)> 
<! 

30 
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The element configentiy contains a declaration of a single configuration property for 
a ManagedConnectionFactory instance. Each ManagedConnectionFactory instance creates 
connections to a specific EIS instance based on the properties configured on the 
ManagedConnectionFactory instance. The configurable properties are specified only once 
5 in the deployment descriptor, even though a resource adapter 202 can be used to configure 
multiple ManagedConnectionFactory instances (that create connections to different 
instances of the same EIS). The declaration consists of an optional description, name, type 
and an optional value of the configuration property. If the connector provider does not 
specify a value than the deployer is responsible for providing a valid value for a 
10 configuration property. Any bounds or well defined values of properties are described in 
the description element An example appears below. 

> 

<!ELEMENT configproperty (description?, configpropertyname* configproperty 
type, configpropertyvalue?)> 
15 <! 

The element configpropertyname contains the name of a configuration property. 
Example: <^nfigpropertyname>SexverNam 

The connector architecture defines a set of well defined properties all of type 
javaJang-String. These are as follows in the examples: 

20 <tonfigpn>pertyname>ServCTNam 

<tonfigpropertyname>PortNum 

<^xmfigpropertyname>UseiNa^ 

<^nfigpropertyname>Password<#^ 

<ttmfigpropertyname>Ckim 

25 The connector provider can extend this property set to include properties specific to a 
resource adapter 202 and its underlying EIS. 

> 

<!ELEMENT configpropertyname (#PCDATA)> 
<! 

30 The element configpropertytype contains the fully qualifies Java type of a 

configuration property as required by ManagedConnectionFactory instance. The following 
are the legal values of configpropertytype: java.IangJBooIean, javaJang.String, 
java,langJnteger,.javaJangJ)odble, java.langJByte, java-lang.Short, javaJangXong, 
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java.lang.Float 

Example: <tanfigpropertytype>java, 

> 

<!ELEMENT configpropertytype (#PCDATA)> 
5 <! 

Hie element configpropertyvalue contains the value of a configuration entry. 
Example: <tanfigpropertyvalue>Wonftat^ 

> 

<!ELEMENT configpropertyvalue (#PCDATA)> 
10 <! 

The element displayname contains a short name for the connector that is intended 
to be displayed by the tools. 

> 

<!ELEMENT displayname (#PCDATA)> 
15 <! 

The element description is used by connector provider to provide text describing the 
parent element The description element includes any information that the connector 
provider wants to provide to the deployer. Typically tools used by the consumer of resource 
adapter module 206 will display die description when processing the parent element 

20 > 

<!ELEMHNT description (#PCDATA)> 
<! 

The element eistype contains information about the type of the EE. For example, 
the type of an EES can be product name of EES independent of any version info. This helps 
25 in identifying EES instances that can be used with this resource adapter. 

> 

<!ELBMENT eistype (#PCDATA)> 
<! 

The icon element contains the name of a file containing an icon image for the 
30 resource adapter module 206. The file name is relative path within the resource adapter 
module 206. This file is be either in JPEG or GIF format The icon is used by tools to 
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display information about the resource adapter module 206. 
Example: 

<icon^Ub/imagesAvombatadapter.jpg<^con> 
> 

5 <!ELEMENT icon (#PCDATA)> 
<! 

The element managedconnectionfectoryclass specifies the fully qualified name of 
the Java class that implements the javax J^oiuxe.ManagedCom interface. 
This Java class is provided as part of resource adapter's implementation of connector 
10 specified contracts. 
Example: 

< toa nagedc^ectionfect^ 
dcoxmectionfectoryclass> 

> 

15 <!ELEMENT man^edconnectionfectoryclass (#PCDATA)> 
<! 

The element reauthenticationsupport specifies whether the resource adapter 202 
implementation supports ^authentication of existing ManagedCoimection instance. Note 
that this information is for the resource adapter 202 implementation and not for the 
20 underlying EES instance. This element is one of the following: 

<3reaQthenticationsupport>t^ 

<reauthenticationsupport>fals^ 

> 

<!ELEMENT reauthenticationsupport (#PCDATA)> 
25 <! 

The element specversdon specifies the version of the connector architecture 
specification that is supported by titds resource adapter 202. This information enables 
deployer to configure the resource adapter 202 to support deployment and runtime 
requirements of the corresponding connector specification. 

30 Example: 

<specversior£>l .0</specversiort> 

> 
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<!ELEMENT specversion (#PCDATA)> 
<! 

The element securityperarission specifies a security permission that is required by 
the resource adapter code. The security permission listed in the deployment descriptor are 
5 ones that are different fiom those required by the definilt permission set as specified in the 
connector specification. The optional description can mention specific reason that resource 
adapter 202 requires a given security permission. 

> 

<!ELEMENT securitypennission (description?, securitypennissionspec)> 
10 <! 

The element securitypermissionspec specifies a security permission based on the 
Security policy file syntax. 

Example: httpy>5ava.sim.com/products^dk/l ,2/docs/guide/security/PohcyF^ 
FileSyntax 
15 > 

<!ELEMENT securitypennissionspec (#PCDATA)> 
<! 

The transactionsupport element specifies the level of transaction support provided 
by the resource adapter. The value of transactionsupport is one of the following: 

20 <transactionsupport>nojbransa^ 

<ttansacticmsupport>localJb^^ 

<transactionsupport>xa_transac^ 

> 

<!ELEMENT transactionsupport (#PCDATA)>.<! 
25 The element vendorname specifies the name of connector provider vendor. 

Example: - 
<vendomame>Wombat Corp.</vendoiname> 

> 

<!ELEMENT vendorname (#PCDATA)> 
30 <! 
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The element version specifies a string based version of the resource adapter 202 
from the connector provider. 
Example: 

<version>l .0<Aversion> 
5 > 

<!ELEMENT version (#PCDATA)> 
<! 

The ID mechanism allows tools that produce additional deployment information 
(beyond the standard deployment descriptor) to store the nonstandard information in a 
1 0 separate file and to refer to standard deployment descriptor from these nonstandard tools 
specific file. Tools cannot add the nonstandard information into the standard deployment 
descriptor. 
> 

<! ATTLIST aiithmechanism id ID #h\4PLIED> 
15 <! ATTLIST authmechtype id ID #IMPLIED> 

<! ATTLIST configpxoperty id ID #IMPLIED> 

<! ATTLIST configpropertyname id ID #IMPLffiD> 

<! ATTLIST configptopertyvarae id ID #IMPLDBD> 

<! ATTLIST configpropertytype id ID iflMPLffiD> 
20 <! ATTLIST connector id ID #IMPLIED> 

<! ATTLIST ccmnecfioiuactorvinterfiice id ID #IMPLffiD> 

<! ATTLIST connectionfiurtoiyimplclass id ID #IMPLIED> 

<! ATTLIST connectioninteriace id ID #IMPLDBD> 
- <! ATTLIST comiecuonimplclass id ID #IMPLIED> 
25 <1 ATTLIST credentialinterfece id ID #IMPLEED> 

<!ATTUST description id ID 3HMPLIED> 

<! ATTLIST displayname id ID #IMPLIED> 

<!ATTLIST eistype id ID #IMPLIED> 

<!ATTLIST icon id ID #IMPLIED> 
30 <! ATTLIST managedcomiectionfactoiyclass id ID #IMPLIBD> 
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<! ATTLIST reauthenticationsupport id ID #IMPLBBD> 

<! ATTLIST resourceadapter id ID #IMPLIED> 

<! ATTLIST securitypermission id ID «MPLB5D> 

<! ATTLIST securitypennissionspec id ID #IMPT,THD> 

5 <! ATTLIST specversion id ID #IMPLIED> 

<! ATTLIST transactionsupport id ID #IMPLIED> 

<! ATTLIST vendomame id ID #IMPT,TRD> 

While a system for a modular and portable deployment of a resource adapter in a 
client server computer environment has been described and illustrated in detail. While there 
10 have been described above the principles of the present invention in conjunction with 

various embodiments, die foregoing description is made only by way of example and not as 
a limitation to the scope of the invention. 
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CLAIMS 

What is claimed is: 

1 . A computer system having a client server architecture, comprising: 
5 an application server, 

an enterprise information system including computing resources; 
a connection provider; 

a resource adapter, said resource adapter implemented by said connection provider 
to serve said resources from said enterprise information system to clients, wherein the 
1 0 resource adapter is packaged with a deployment descriptor to form a resource adapter 

module corresponding to a J2EE module hierarchy, wherein said resource adapter module is 
deployed into the application server to allow multiple J2EB applications to share the 
resource adapter module; and 

a deployer, said deployer using a deployment tool to configure the resource adapter 
IS into a target operational environment, the deployment tool capable of reading the 
deployment descriptor. 

2. The computer system of Claim 1, wherein the resource adapter module specifies a 
level of transaction support pro vi ded by the resource adapter. 

20 

3. The computer system of Claim 2, wherein the level of transaction support indicates 
no transaction support 

4. The computer system of Claim 2, wherein the level of transaction support indicates 
25 local transaction support 

5. The computer system of Claim 2, wherein the level of transaction support indicates 
resource manager local transactions are supported 

30 6. The computer system of Claim 5, wherein local resource manager transactions are 
supported by implementing a LocalTransaction interface. 
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7. The computer system of Claim 2, wherein the level of transaction support indicates 
JTA transactions are supported. 

8. The compute system of Claim 7, wherein JTA transactions are supported by 
5 implementing an XAResource interface. 

9. The computer system of Claim 2, wherein the deployer configures the application 
server for transaction management based on the level of transaction support specified by the 
resource adapter. 

10 

10. The computer system of Claim 1, wherein the connection provider specifies name, 
type, and description for properties that have to be configured on a per connection factory 
instance basis, wherein the properties determine connections to a specific enterprise 
information system instance. 

15 

11. The computer system of Claim 10, wherein the connection factory instance is 
registered in a JNDI namespace. 

12. The computer system of Claim 1, wherein the connection provider specifies 
20 authentication mechanisms that are supported by the resource adapter. 

13. The computer system of Claim 1, wherein the deployer configures the application 
server for transaction support based on the level of support specified by the resource 
adapter. 

25 

1 4. The computer system of Claim 1 , wherein the connection provider specifies whether 
the resource adapter supports reauthentication of an existing physical connection. 

15. The compute: system of Claim 1, wherein the deployment tool is provided by the 
30 application server. 
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16. The computer system of Claim 1 , wherein the deployment descriptor defines a 
contract between the connector provider and the deployer. 

17. A computer program product, which, when executed by a computer, implements a 
5 client server compute: system by performing the steps of: 

providing an application server; 

providing an enterprise information system including computing resources; 
providing a connection provider; 

providing a resource adapter, said resource adapter implemented by said connection 
1 0 provider to serve said resources from said enterprise information system to clients, wherein 
the resource adapter is packaged with a deployment descriptor to form a resource adapter 
module corresponding to a J2EB module hierarchy, wherein said resource adapter module is 
deployed into the application server to allow multiple J2EE applications to share the 
resource adapter module; and 
15 providing a deployer, said deployer using a deployment tool to configure the 

resource adapter into a target operational environment, the deployment tool capable of 
reading the deployment descriptor. 
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